Designer - Defining and using type conversion definitions

Preface

As discussed in Concepts - Type Converters, the easiest way to work with type converters in the designer is to define in an existing project a set of type conversion definitions. This section guides you through the steps to create a basic type converter definition using the shipped type converter for converting int/byte etc. to System.Boolean and back.

Creating a new / editing an existing type conversion definition

After loading a project, you can open the type conversion definition dialog by selecting "Edit Type Conversion Definitions..." from the context menu when you right-click the project node in the Project Explorer, or select it from the Project menu in the LLBLGen Pro gui. If no type conversion definition currently exists, you'll see this dialog:



By clicking Add new..., you'll be able to define a new type conversion definition using a new dialog:



As type conversion definitions are used to set type converters on fields, the first thing you've to specify is the original type the type conversion has to work on. This type is then used to determine which type converters accept values of that type for conversion. As our example type converter accepts int/byte etc., we selected Int32 as the type to work on, and LLBLGen Pro will then enlist the type converters found which accept that type. In our situation, we select the BooleanNumericConverter type converter.

After clicking OK, you'll see a type conversion definition in the listview at top of the main type conversion definition dialog. This type conversion definition is already usable, though when used, it matches all fields which have an original .NET type of System.Int32. If this type conversion definition is supposed to be applied automatically, it will match perhaps with fields which shouldn't get the BooleanNumericConverter as type converter.

To solve that, you can specify up to four filters which can be enabled by checking their specific checkbox:

• Database type. With this filter you can define on which Database specific type, like NUMBER, or unique_identifier, the type conversion definition has to work on. The types listed in the drop down box are all the database types supported by the project's database driver. Note: it can be a type isn't listed though the target database supports it, for example INTEGER on Oracle. These types are synonyms for existing types and you should pick the real database type instead.
• Length. With this filter you can define what the length setting of the field has to be to let it match with the type conversion definition. Use this only for type conversion definitions which have a non-numeric type to work on, like string.
• Precision With this filter you can define what the precision setting of the field has to be to it match with the type conversion definition. Use this only for type conversion definitions which have a numeric type to work on, like Int32.
• Scale With this filter you can define what the precision setting of the field has to be to it match with the type conversion definition. Use this only for type conversion definitions which have a fractional numeric type to work on, like Single.

All filters are used on top of the filter on the type the type conversion definition works on. This means that selecting a database type which won't result in the .NET type the type conversion definition works on, the type conversion definition will never match any field.

When working on fields to apply type conversion definitions, the type conversion definition which matches the most filters is selected. If two or more type conversion definitions match a given field, the one which is found first, is selected.

When you're satisfied with your type conversion definitions, click OK to close the form. Don't forget to save your project.

Note:

Deleting a type conversion definition doesn't remove the set type converter definitions on fields. It only removes the type conversion definition.

Using existing type conversion definition

Type conversions are meant to make it very easy, even automatic, to set type converters on fields. For example, in a large Oracle project, you'd likely define a type conversion definition using the BooleanNumericConverter which applies to NUMBER, and precision 1 and scale 0. This then makes sure that only fields which are mapped onto target fields with database type NUMBER(1,0) will get the type conversion definition applied and thus get the BooleanNumericConverter set as their type converter. The type conversion definition can then be used to automatically apply the BooleanNumericConverter to any field matching the filters set for the type conversion definition.

Setting type converters by using a plug-in

LLBLGen Pro comes with a plug-in, which is able to apply the checked type conversion definitions by searching through all the fields in the selected entities and typed views. This plug-in is called "Assign type converters plug-in", and can be activated through the context menu on the "Entities" or "Typed Views" node in the project explorer and then by selecting the plugin from the Run Plug-in context menu, or by right-clicking an entity or typed view and then by selecting the plug-in from the Run Plug-in context menu.

Setting type converters automatically

In a larger project, you don't want to run plug-ins from time to time, you want the designer to take care of the application of the type conversion definitions automatically, so that when you add a new entity, typed view or through a refresh of the catalog(s) new fields are added / new entities are added, the necessary type converters are set automatically. To achieve this, you just have to set a preference setting, which is inherited by a new project (so if you change the preference while having a project loaded, you have to change it also in the project properties), to true: set AutoAssignTypeConverterToNewField to true, and LLBLGen Pro will make sure that all type conversion definitions are matched to any new field's type and db type definition, and the best match is selected and used to set the type converter for that field. If no type conversion definition matches, no type converter is set and the field keeps its original .NET type supplied by the used database driver.